1999 Technotes

December 1999

New

• TN1192: ATA Interface Modules

  This Technote describes how to write a device driver for an ATA host bus controller, known as an ATA Interface Module, or AIM. An AIM is the ATA equivalent of the SCSI Interface Module (SIM). It does not control a device on the ATA bus, but implements a standard hardware abstraction for the bus itself.

  AIMs operate at the very lowest level of the traditional Mac OS I/O subsystem, which makes them hard to write and hard to debug. Only experienced Mac OS device driver writers should consider developing an AIM.

  This Note is directed at developers of ATA host bus controller cards (typically PCI or CardBus).

Updated

• TN1141: Extending and Controlling Sherlock
  

  Mac OS 8.5 includes several enhanced searching capabilities, known collectively as Sherlock. Previously, the Mac OS Find application allowed users to search mounted disk volumes for files based on information such as name, modification date, and file type. Sherlock retains this functionality, but also extends the user’s search options to include both the content of files and the Internet.

  Sherlock 2 adds a number of new features to the array of search options presented to the user. To accommodate those new features, some additions have been made to the Internet Search Plug-in language, new applescript commands have been added. Where appropriate, these new features are described in this document.

  Find by Content library information formerly found in this note has been moved to Technote TN1180, "Sherlock's Find By Content Library."

  
  
• TN1104: Interrupt-Safe Routines

  The traditional Mac OS has a badly defined set of heterogeneous programming environments. In some of these environments, your code can access some system services but not others. Furthermore, the names given to these environments are often overloaded and confusing. This results in a lot of programmer confusion.

  This Technote attempts to clear up this confusion by assigning each of the execution levels a unique name, describing how and why your code might find itself running at a particular execution level, and outlining the restrictions your code might face when running at that level.

  This Technote is important for anyone programming any Mac OS code that might run at "interrupt time," and vital for anyone doing system-level programming under the traditional Mac OS.

• TN1176: Mac OS 9

  This Technote discusses changes and corrections in the next generation of Mac OS: Mac OS 9. This system follows Mac OS 8.6 and contains several enhancements and revised features.

  All developers interested in creating products compatible with Mac OS 9 will want to review this document.

November 1999

New

• TN1191: USB Software Update

  This Technote describes the live software update process under Mac OS 9.0 and the support which it provides for USB devices. It explains how developers can register with DTS to have access to the USB Update Database. The developer updates the database to provide information which the Software Update process uses to download the appropriate software for the USB Device.

  
  
• TN1190: Power Manager 2.0

  The Power Manager 2.0 is an update to Mac OS that facilitates the implementation of a more aggressive power management policy, supports new capabilities in the latest Macintosh hardware and the NewWorld ROM architecture.

  Power Manager 2.0 is available on all iMacs, blue & white G3 and Power Mac G4 desktops, the "bronze keyboard" PowerBook G3 Series, the iBook, and future portables and desktops.

  While internal changes have been made to the Mac OS to support Power Manager 2.0, there are a few new API routines that are available to developers. Thus, this document describes the features new or updated in Power Manager 2.0. For complete details on using Power Manager services, please see the chapter "Power Manager" in Inside Macintosh: Devices.

  This Note is not only directed at application developers who previously had concerns about running on portables, but indeed to all Mac OS application developers. Device Driver writers on the other hand should review Updating Drivers for PM 2.0, for detailed information on how to support removal of power to the PCI slots.

  
  
• TN1189: The Monster Disk Driver Technote

  This Technote is both a summary and review of existing disk driver information and a description of disk driver features that until now have not been generally documented.

  This Note is directed at developers of disk drivers and disk formatting utilities. There is also a section specifically aimed at application developers who need to operate on disks directly.

  
  

Updated

• TN1187: Digital CD Audio

  Starting with Mac OS 9.0 there is a new way of playing CD audio— digitally. Pure digital data is read from the CD, played through the Sound Manager as a PCM (Pulse Code Modulation—standard uncompressed audio) data stream, and then sent out to the speakers (where your ears require that it be converted back to an analog signal). This Technote describes how an application uses the new digital CD audio support and what a CD or DVD driver needs to do to support playing audio digitally.

• TN1141: Extending and Controlling Sherlock
  

  Mac OS 8.5 includes several enhanced searching capabilities, known collectively as Sherlock. Previously, the Mac OS Find application allowed users to search mounted disk volumes for files based on information such as name, modification date, and file type. Sherlock retains this functionality, but also extends the user’s search options to include both the content of files and the Internet.

  Sherlock 2 adds a number of new features to the array of search options presented to the user. To accommodate those new features, some additions have been made to the Internet Search Plug-in language, new applescript commands have been added. Where appropriate, these new features are described in this document.

  Find by Content library information formerly found in this note has been moved to Technote TN1180, "Sherlock's Find By Content Library."

  
  
• TN 1104: Interrupt-Safe Routines

  The traditional Mac OS has a badly defined set of heterogeneous programming environments. In some of these environments, your code can access some system services but not others. Furthermore, the names given to these environments are often overloaded and confusing. This results in a lot of programmer confusion.

  This Technote attempts to clear up this confusion by assigning each of the execution levels a unique name, describing how and why your code might find itself running at a particular execution level, and outlining the restrictions your code might face when running at that level.

  This Technote is important for anyone programming any Mac OS code that might run at "interrupt time," and vital for anyone doing system-level programming under the traditional Mac OS.

  
  
• TN1041: Inside Macintosh: Files Errata

  This Technote discusses known errors and omissions in Inside Macintosh: Files.

  
  
• IC_505: Apple Event Manager Q&As

  This Technote contains a collection of archived Q&As relating to a specific topic--questions sent the Developer Support Center (DSC) along with answers from the DSC engineers. Current Q&A's can be found on the Macintosh Technical Q&A's web site.

  
  
• FL_30: Resolving Alias Files Quietly

  ResolveAliasFile always presents the user identity dialog when mounting remote volumes. This Technote offers an alternative function, ResolveAliasFileMountOption, which uses the previously undocumented FollowFinderAlias trap to resolve alias files only if the target is on a volume that has been mounted. Also included is an IsAliasFile routine for identifying alias files.

  A new routine, ResolveAliasWithMountFlags, was introduced with Mac OS 8.5.ResolveAliasWithMountFlags is identical to ResolveAlias with the exception that it provides the mountFlags parameter allowing callers to suppress disk switch alerts. The mountFlags parameter can be set to kResolveAliasFileNoUI to prevent any user interaction, including disk switch alerts, while the alias is being resolved. See Technote Mac OS 8.5 Technote: Part IX for usage details.

October 1999

New

• TN1188: Packages in Mac OS 9

  This Technote describes how the Finder implements packages in Mac OS 9. Developers interested in creating packages for use in Mac OS 9 can use this document as a guide for creating packages. Mac OS 9 packages offer a simple consolidated experience for the user when interacting with a package in the Finder's windows, while at the same time preventing accidental tampering with a package's required support files. For Mac OS X package compatibility, an additional package specification for Mac OS X will be released as an adjunct to the Mac OS 9 package specification described in this document. Upon release of this additional specification, developers will be able to create packages to be used in either Mac OS 9 or Mac OS X.

• TN1187: Digital CD Audio

  Starting with Mac OS 9.0 there is a new way of playing CD audio— digitally. Pure digital data is read from the CD, played through the Sound Manager as a PCM (Pulse Code Modulation—standard uncompressed audio) data stream, and then sent out to the speakers (where your ears require that it be converted back to an analog signal). This Technote describes how an application uses the new digital CD audio support and what a CD or DVD driver needs to do to support playing audio digitally.

• TN1186: How To Be a Good Multiple Users Citizen

  This Technote describes the new APIs provided by the Multiple Users technology introduced in Mac OS 9.0. It also answers the most frequent questions from developers and provides a few workarounds for commonly encountered problems. This Note is directed at application developers who are accessing folders within the System Folder or using the FindFolder API and need to pay extra attention to the access privileges of those folders.

• TN1185: New ColorSync 3.0 APIs

  This Technote describes the APIs your application can use to take advantage of new features available in ColorSync 3.0.

• TN1184: FCBs, Now and Forever

  Mac OS 9.0 changes the format of the File Control Block (FCB) table significantly. This technote explains the original format of the FCB table, how the use of the FCB table has evolved over time, and how you can access FCB information in a compatible way. All Mac OS developers should read the Concrete Advice section to ensure that their software is compatible with Mac OS 9.0 and beyond. If your software is not compatible with Mac OS 9.0 (specifically, it causes a system error 119), you should read the Debugging FCB Problems section. The other sections of the technote are background material for the Mac OS archaeologists out there.

• TN1183: QuickTime 4.0.3

  QuickTime 4.0.3 can be described as a minimal-changes release that provides a number of miscellaneous bug fixes. This Technote describes the changes made between the final release of QuickTime 4 and the update release of QuickTime 4.0.3.

• TN1182: NewGWorlds in VRAM and AGP Memory

  This Technote describes the changes in NewGWorldNewGWorld with the release of Mac OS 9. The NewGWorldNewGWorld routine now supports allocation of offscreen GWorld’s in AGP memory and VRAM. This allows the application programmer much more flexibility in deciding how to allocate their off-screen images. It also adds more complexity and can, if used incorrectly, result in significantly poorer application performance. This Technote describes the new selectors, covers their basic use, then goes on to illustrate some of the basic problems associated with their use. Finally, the note discusses basic performance figures from a sample implementation.

• TN1181: Sherlock’s Find by Content Text Extractor Plug-ins

  This Technote describes the API for creating Find By Content Text Extractor Plug-ins. Text Extractor Plug-ins are used by Find by Content to extract the textual information stored in a document when it is creating indexes and summarizing files. By doing so, it is possible for users to avoid indexing peripheral data such as formatting commands, HTML tags, and other data that does not relate to the information stored in the document. By creating Text Extractor Plug-ins for their document types, developers make it possible for users to conduct meaningful searches for information stored in documents created by their applications. This Technote provides information necessary for creating and installing Text Extractor Plug-ins. In addition, an annotated example Text Extractor Plug-in is provided. Developers can easily modify this example to create their own plug-in for use with their own file formats.

• TN1180: Sherlock’s Find By Content Library
  
  

  This Technote describes the Find by Content libraries used by Sherlock for searching the contents of files. The Find by Content libraries export a full suite of routines and functions allowing applications to perform content based searches of files. With MacOS 8.6, Text Extractor Plug-ins were introduced. These allow Find By Content to extract textual information from binary files for inclusion in index files. Text Extractor Plug-ins are documented in Technote TN1181, “Find by Content Text Extractor Plug-ins.” This Note is directed at application developers who wish to access the Find By Content library directly from their applications.

• TN1179: PostScript Output Filters For LaserWriter 8.7

  LaserWriter 8 version 8.7 introduces the concept of PostScript output filters and their use during printing. PostScript output filters are code fragments that live in the data fork of files that reside within the “Printing Plug-ins” folder contained in the Extensions folder. These code fragments can intercept the PostScript output data stream generated by LaserWriter 8 and add, remove, or modify the data before it is transmitted to the output device. Through this type of modification, a PostScript output filter can implement customized control of features for a specific printer model or can implement new user features across a range of PostScript printers without requiring changes to LaserWriter 8. The remainder of this document refers to PostScript output filters as “filters” or “plug-ins.”

• TN1178: LaserWriter 8.7: Scriptable Printing
  
  Until the introduction of PrintingLib 8.7 (which is included with LaserWriter 8, Version 8.7), it has been impractical for an application to extend the scriptability of the Print Documents Apple event. The application receives the print event, but the printer driver controls and uses the settings for the print job. In addition, the print settings used by each driver have been different. This document details the extensions to the print event that allow scripters to control printing. This document also describes the changes applications and printer drivers must make to support these new scriptable printing features.
  
  
• TN1177: Introducing the LaserWriter 8 Driver version 8.7
  
  This Technote outlines some of the new features and changes that Apple has made in the LaserWriter 8 version 8.7 driver (released as part of Mac OS 9). It describes expanded technology and user interface support and what these mean to the developer community. LaserWriter 8.7 is only available as part of Mac OS 9 and can only be run on PowerPC machines running Mac OS 9.
  
  
• TN1176: Mac OS 9
  
  This Technote discusses changes and corrections in the next generation of Mac OS: Mac OS 9. This system follows Mac OS 8.6 and contains several enhancements and revised features. All developers interested in creating products compatible with Mac OS 9 will want to review this document.

Updated

• TN1063: Inside Macintosh: Processes: Time Manager Addenda
  
  This Note highlights the usage of two fields -- tmReserved and tmWakeUp -- that might be unclear after reading the chapter "Time Manager" in Inside Macintosh: Processes. This Note is intended for all developers who want to do time measurement using the Time Manager routines.
  
• TN1059: On Improving Open Transport Network Server Performance

  As higher network datalink speeds become more commonplace, Mac OS server performance has come under closer scrutiny. Developers who write network server applications on the Mac continue to be concerned about performance issues. In many cases, server throughput and connection latency problems may stem from poor application design rather than any deficiencies in Open Transport or the Mac OS. This Technote is intended for Macintosh developers writing network server applications that use the Open Transport API, and discusses some techniques you can employ in your network server application design to achieve higher performance.

September 1999

New

• TN1175: Applet Signing with MRJ and Javakey

  Applet signing has been the topic of considerable discussion throughout the Java community. Processes and procedures related to the signing of applets are generally complex and sometimes confusing, and users have had issues related to using and signing applets with MRJ. The purpose of this document is to discuss the technology being employed and to clarify the procedures needed to sign jar files, install certificates, and successfully utilize a signed applet.

• TN1174: Optimization Strategies for Mac OS
  

  Performance tuning is a critical part of all application development. Customers don’t like sluggish applications, and are willing to vote with their money. The good news is that small changes in an application can result in solid increases in the overall performance. This technote attempts to gather a significant amount of lore on tuning Mac OS applications for the best possible performance.

August 1999

New

• TN1173: Understanding Open Transport Asset Tracking
  

  This Technote describes the asset tracking mechanism used for the existing Open Transport programming interface, and how that mechanism has been “tuned up” for Carbon. It is directed at all programmers who use the Open Transport client programming interface.

• TN1172: Writing Plug-ins for Desktop Printer Utility
  

  This document describes how to write plug-ins for DTPU version 1.2 and later. A DTPU plug-in is a mechanism for programmers to write shared libraries which can be recognized by DTPU and provide means to configure different types of desktop printers that are not built into DTPU. A good use of this is to provide user interface for configuring external hoses for LaserWriter 8.

Updated

• TN1144: Writing Custom Hoses For LaserWriter 8.6
  

  LaserWriter 8, Versions 8.6 and later, supports printing to a variety of desktop printer (DTP) types, including PAP, LPR and IrDA. Each desktop printer can have its own method of communicating with its associated physical printer, RIP, or other post-printing processor. LaserWriter 8.6, through the invention of custom “hoses,” added the ability for shared libraries to implement various communication methods and for these libraries to be loaded dynamically based upon a DTP’s type. This Technote gives an overview of the custom hose specification for developers.

• TN1126: A Checklist for Building Applications and Extensions
  

  This Technote tries to summarize all of the different items which you need to include to build a good, well-behaved Macintosh product. In August 1999, this document was updated to correct the Rex definition of CCI.

June 1999

New

• TN1171: LaserWriter 8.6: How to Write a Converter Plug-in for the Download Manager
  

  This document describes in detail how to write a plug-in converter module for use with the Download Manager under PrintingLib version 8.6 (included with LaserWriter 8 version 8.6) and later. It contains information about the pieces a plug-in must have, discussion of a sample plug-in and tips for plug-in developers. This Technote is directed at application developers who wish to write plug-in converters.

• TN1170: The Printing Plug-ins Manager
  

  The Printing Plug-ins Manager is intended to make it straightforward for software clients to create, load, and use shared libraries which can be treated as printing plug-ins. The Download Manager has been implemented using the Printing Plug-ins Manager to manage its plug-ins. Future printing software will use the Printing Plug-ins Manager to manage other plug-ins. This Technote is directed at application developers who wish to write plug-in modules.

• TN1169: The Download Manager
  

  This Technote discusses the Download Manager API that Download Manager clients would use to call the Download Manager to cause a file, or other data, to be downloaded to a PostScript printer. (The Desktop Printing software is an example of a Download Manager client that uses this API.) Furthermore, this Technote examines the APIs that the Download Manager uses to call the low-level converters. This material is intended for the writers of the low-level converters which are called by the Download Manager.

Updated

• TN1144: Writing Custom Hoses For LaserWriter 8.6
  

  LaserWriter 8, Versions 8.6 and later, supports printing to a variety of desktop printer (DTP) types, including PAP, LPR and IrDA. Each desktop printer can have its own method of communicating with its associated physical printer, RIP, or other post-printing processor. LaserWriter 8.6, through the invention of custom “hoses,” added the ability for shared libraries to implement various communication methods and for these libraries to be loaded dynamically based upon a DTP’s type. This Technote gives an overview of the custom hose specification for developers.

• TN1161: Extending the Print Record for LaserWriter 8
  

  This Technote describes what changes need to be made in your application to support drivers that use extended print records in LaserWriter 8.